How to Implement 
Context-Sensitive Help 



BY RAY DUNCAN 



s graphical user interfaces 
have become the standard, 
and on-Une documentation 
has become a mandatory 
component of commercial 
software, developers have 
looked around for new ways 
to differentiate their prod- 
ucts from those of their com- 
[petitors. One of the more recent and 
[ clever innovations in the area of on-line 
help is context sensitivity. A software 
product with this feature responds to the 
user's request for assistance according to 
' what the user is currently doing, instead 
of simply displaying the help file's main 
table of contents and expecting the user 
to navigate to the appropriate topic. For 
example, if the user presses the Fl key 
while the Save As dialog box is on the 
screen, the application will jump directly 
to a help screen that explains the con- 
straints on filenames, how to change di- 
rectories within the dialog, and so on.. 

When you first consider adding con- 
text help to your own program, you'll 
probably guess (as I did) that a first ap- 
proach to solving the problem is simply 
keeping track of the mouse p(»nter and 
responding to WM.CHAR or WM_ 
KEYxxx messages based on that posi- 
tion. However, a few moments of addi- 
tional musing on the common Windows 
user interface widgets will quickly con- 
vince you that the problem must actually 
be more complioited. For example, the 
grunt work of displaying a menu pop-up 
on the screen, tracking the mouse within 
the pop-up, highlighting the menu item 
under the mouse pointer, and decoding 
the user's menu selection is all taken care 
of magically by USER.EXE; from the ap- 
pUcation's point of view, all it knows is 
ihat it gets a WM_INITMENU message 
before the menu is displayed and a 
WM_COMMAND message after the 



user has made a selection. Dialog han- 
dling, which allows for , arbitrary combi- 
nations and groupings of controls, is even 

more magical. 

, As it turns out, there's more than one 
way to solve the context-sensitivity help 
problem. Windows is an exceedingly rich,, 
complex environment, and the program- 
mer who really wants to peek inside the 
environment's handling of menus and di- 
alogs can find several ways to subvert 
these ordinarily atomic operations. The 
approved method, however, is for the ap- 
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sample code. 

pUcation to register a Windows hook. A 
hook is nothing more than a callback pro- 
cedure within the application that is 
entered by Windows when certain events 
occur, the application can filter the events 
by ignoring them, altering them, consum- 
ing them, or responding to them as it sees 
fit. Many classes of Windows applica- 
tions, ranging ftcm word processors to 
testing programs to debuggers, rely on 
the Windows support for hook proce- 
dures. 

Before we go any farther, I should 
mention that there are two parallel APIs 
in Windows for the installation, process- 
ing, and deinstallation of Windows 
hooks. Hie Microsoft manuals and SDK 
example programs all focus on the older 
API, consisting of SetWindowsHookQ, 



UnhookWindowsHook(), and Def- 
HookProcQ. However, in this column, 
I'm only going to demonstrate the use of. 
the hook API functions that first ap- 
peared in Windows .3.1 — Set- 
WindowsHookEx(), UnhookWindows- 
HookExQ, and CaUNextHookExO- The 
newer functions have a much cleaner de- 
sign and have the additional advantage 
that they are symmetric with the hook 
functions in the WIN32 API.s~ 

CONTEXT-SENSITIVE HELP Adding any 
form of context-sensitive help to your ap- 
plication is a multist^ pnxxss where all 
the elements must be coordinated and 
work smoothly together. In this column, 
I'm only going to show you how to imple- 
ment an extremely simplistic form of con- 
text-sensitive help to a Windows pro- 
gram. If you've used elaborate on-line 
help systems such as the one in Microsoft 
Excel 4.0, you can imagine that the code 
in such a program devoted to context- 
sensitive help alone might well outweigh 
the totality of die applications written by 
us humbler developers! I'll leave such so- 
phisticated implementations to your own 
creativity and experimentation. 

Assume that we are starting with a 
working but vanilla Windows appUcation 
that has a Help pop-up on its menu bar 
and an accelerator table that equates the 
Fl key to the Help Contents menu item. 
When the user picks the Help Contents 
menu item or presses the Fl key, the ap- 
plication launches WINHELP.EXE with 
the name of its help file to display the 
help table of contents. We want to modify 
the application so that if the user presses 
the Fl key while a pop-up menu is active, 
the help viewer displays the help topic 
that describes the appUcation's menu se- 
lections rather than the usual table of 
contents. We can reach this goal by in- 
stalling a windows hook function that 
sees every message generated by the 
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user's interaction with the application. 
The hook function will monitor for an Fl 
keystroke while a menu is active and will 
react to the keystroke by sending a spe- 
cial message to the application's main 
message handler. The main message han- 
dler will then activate the help viewer and 
Steer it to the appropriate topic. 

The first step in the implementation 
of this simple context-sensitive help is to 
prepare the help file. For those occasions 
when we want to display a specific topic 
rather than the table of contents, we must 
give the viewer a way to associate integer 
values passed by the appUcation in a Win- 
HelpQ call with the context strings that 
are used internally to the help file as the 
targets of hyperlinks. This association is 
accompUshed by adding entries to the 
[MAP] section of the help project (.HPJ) 
file that controls the compilation of the 
ultimate help (.HLP) file. For example, 
imagine that we are building the file 
EXELOOILHLP that contains the on- 
line documentation for the program 



EXELOOK.EXE. To assign the integer 
identifier 1 to the EXELOOK.HLP topic 
labeled by the context string menu_ 
index, we would edit the following lines 
mto the EXELOOKJEIPJ ffle: 

[MAP] ■ 
]iienu_lndex 1 

and then rebuild the EXELOOK.HLP 
file with the command: HC EXELOOK. The 
next steps would be to add code to the 
initialization sequence of the application 
to register a private window message for 
use by the hook function with Register- 
WindowMessageQ, then allocate a thunk 
address for the hook procedure with 
MakeProcInstanceO, and install the 
hook function with SetWindows- 
HookEx(). One of the parameters for 
SetWindowsHookEx() is a code that de- 
termines what type of events will be 
passed to the hook procedure; in this 
case, we'd use tiie code WH_MSGFIL- 
TER, which means we want our hook 



procedure to be notified for eye 
sage that is related to our applicaSqis 
not for any other type of "hoo 
event. SetWindowsHookExQ re*" 
hook handle that must be sto' 
global variable for later use. Of 
code must also be added to the pro 
cleanup sequence to remove th 
procedure from tfie chain of all sue 
backs by calling UnhookWin 
HookExQ with the hook handle, mT 
tionally) to release the thunk 
with FreeProcInstanceQ. ' 

Now we must write the hook 
procedure itself, using the guideline 
the Windows API function reference,! 
the particular type of event filtenur 
our procedure is going to perfo 
hook procedure is always called $a 
Windows with three parameters: r-" 
ger referred to as nCode that cla 
the event, a 16-bit value whose me 
depends on the event type, and ^ 
value whose significance also depen 
the event type. In the case of me" 
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//'Skeleton code for context-sensitive Help 

// in a Windows 3.1 application. 
.;;// Ct^jyrighC (C) 1993 Ray Duncan 
rlf PC Magazine *. Zi£f Davis Publishing " 

// string used Co allocate private message mimber''"^' 
,// for use by application's windows hook callback 
• tdaf in* HDOKMSGSTRING : "HelpHookHessager^ nZi'^' . , 

// contact ID for context-sensitive help, must be 
' // synchrtmized with the [HAP] section of HPJ file, 
tdefine MKNO__INDEX_HELP 1 . - 

// far pointer to windows hook callback 
WNDPROC IpfnWindowsHookProc ; 

// handle for frame window 
HWMD hwndFrame = NULL; 

// program instance handle. 
HANDLE hinst;- 

//-'handle for windows hook function ^• 
HHOOK hWindowsHook; 



/ Table of window messages supported by FrameWndProc O 
/ and the functions which -.corrc^pcnid. to each message. . 
/ The first: slot is filled in with & private message number 

/ by InitIr!Stance{ ) . 
/ 

truct decodeWord messages [] = { 
DoHelpContext, 
WM_CREATE, DoCreate, 
WM_INITMENU, DoInitMMiU, - 
WH_SI2E, DoSize. 
.. HK_CO»UUID, DoCommand. . 
WM_CLOSE, OoClose, 
WH_DESTHOY, DoDestroy, ) ; 



// WLifllainO ia ebe usual opplicaCim oicry point 



HIT ftPIBNTRy WinHaindOUIDLB hlnatanca, BKMDLE hPTevlnstance. 

LPSTR IpszOadlCine, HIT nCmdammr) 



// save instance haiuile 
hinst ■ h ln sta nc e,- 

// It this Is the Cizst instance q£ the o^licatiut. 
// -ragisttfr window clasinst^'or eidt * ' ^ r,- -" ; 

if ( ihPrevInstance) 
I 

if (llnltAppO) 

return (FALSE) ; 



// Create Ctaa frane and do other-, instance-^tecific 
// iiUtiaXlsatioa,. or exit . . 

if ( I InitlnetMce ( IpssCmdLlne. - aCad^ow) ) 
retum<n>LSB) ; 



while (GetHessage(&msg, HULL, 0, 0)) // 



r wkile 



// translate virc keys 
//: di^atcar ■asoage 



TranslateHessage (&msg) ; 
DispatchMessage<&msg) ; 



// clewiv all allocations 

«();.. . - . 



// 

// Initlnstance ( ) — Performs a per-inscance initialization 
/ / of application, creating the frame window, allocating 
// private m es a ag ea, etc. Returns TRUE i£ initialization 
// succMsfta, tKiSB otherwise. 

// 

BOOL Initlnstance (LPSTR ivOadLiiM. uznt ncmdshow) 



// allocate private Message nuBber for use 
// windows hook callbacdc pxQcmduxm 
B[l| .Code - 

Regiaterwli^owMessage(<LPSTR| HOOSiSSSnUHS) ; 



if {nessages[BI .Coda ' 
return (raLSB) : 



// alltKAta thunk for windows hook callback 
IpfnWindowsHookProc = 

MafceProc Instance < (WIDPBDC) HindowsHookProc, hInst) 
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^^^ball ■^t if thimk allocation failed 
if (lp£n«indow«HookProc «» NULL) , ; 
. retnixn( FALSE) ; , 



. // register wixuiowa boojc callback and sav« handle 
»_ hWindo*raHook I^^^^'TtC; ■ r - ' ,-■ V ff'*: 

Vi " j,-!r SetWi]adowsHoo>£x'(HlCMSGFILTBR; IpfnWindowaHookProc, 
v^V' ' - . hlnsC, GetCurrentTask f ) ) ; 




. return (TRUE) ; 



// Termlnatanee { ) — global cleanup for application instance. ' 



BOOL Termlnstance (VOID)- 



..ill 



1' ;^m'0i4fi|t:s^ ,. 

// delete our' windcmts hoo)c functloii froa globali chain 



aiihookWindowsHookBx(hHiiidawsapolcl:,>^; 



// release the thunk for our windows callback' 

FreeProcInstancedpfnwlndowsHookProc) ; ■ ■ 



return (TRUE) ; 



//- PraineHndProc{>'i;receivea'.all. measages fori the. Crane window. 

It: looks''i]pj^tJi*rnin#''ne8Sag«^ur tl^.tabl«'M and - 

// dlspat^bfts th*-appz^rlaCe'rcHiciii«' jLf.V'MCch.ia.^i: 
■ // otharwls^ifc^o»U«:.DefWindowPro^ 

LONG, FAR.PASCu|FraBeKider9C(RHHD.<>j^^ 



// pass message on to the other windows books procs in chain 
retum(CallllextHookEx(liMliidowsaook, nCode, wPaxaa, IpMsg} } ; 



for(i = 0; i < dim(messages) ; i++) ,^ 

; t - 

' iffuMsg =~ messages [i] .Code) 
y-^'r.'-J' ratuznt (*1iiessages(il .Fxn) (hHbd, wMsg, wParan, iParaa) ) ; 



return (De£WindowProc(hWndi 




.// l4oHelpContext{) — this routlaa' la'^callftd by I '^r' . ~ 
// PrameWndProc { ) for processing off; tfaa'^ private i&4ssage ^ 

.// sent by the windows hook- procedurW.. J J[tSv,*\.Sit^l^f L'W ' "H;.i,£ji^ 
■// invoke;; the help file viewer with a 'cdntextTiID ' ■-. ' * ■;. 
-'II in order to deliver context -specific^ help.: - . ^ :/ 

//■■:■ • ' 

static LONG DoHelpContext (HWND hvmd. UIOT vMsg, 
UINT wparam, LONG IParam) ; > . . J ■ 

-WinHelp(hHnd, szHelpPileName, HHI^_CONTEXT, MSWU^IKDEXLJIELP) ,• 
■ retum.(FALSE) ; ■ - - ^''-^/-'^^'/^ 

■;/'j?;WindoiraHookProc'7r- windows hook callback function^ . - ' 
■ /A'lliis function nnjat'be'reglatered with SetwindowsHooJcExlj 
// and exported In the application DBF file. 

■ // ; ■ " 

DWORD FAR PASCAL WindowaHookProc (INT nCode. OINT wParam, IJHSG IpMag) 
^ .^^oatlback'^niiltnowri' type. or if pointer 



f^'S/Artb'i 

-If((nCode ■ 

fetum(CallNextHookR)e(hWlndowsIk>ok.. nCode, "wParamj IpHagJ^ )■■,-* 



iasags^sunictur* 'Ia boCv intXid 
le < B) '"| r ilpHag) ' 



// check i£-;;thi^ is F3;. keypress, during,. a nenulpopi^i 
if (nCoda 'MSG^>B»tn'''-T^?^^ ' 
If ( (lpl(sg->auM9«-«WCJSyn3Hnr ' > 



... ^ 



It yes, ~^ post private message nunber to 
. //- our frame window's laeaaage handler 

PoBtHe8sage(hwndFrame, inessages[0] .Code, 
nCode, lpBsg->hwndJ ; 



events, nCode specifies whether a menu 
or dialog is active, the other 16-bit value 
is unused, and the 32-bit value is a far 
pointer to the msgQ structure containing 
(among other things) the familiar values 
hWnd, wMsg, wParam, and LParam. We 
design our hook procedure to test nCode 
for the value MSGF_MENU, then access 
the msgO structure via the 32-bit pointer 
and check for the message type 
WM.KEYDOWN and the virtual key 
value for the Fl key. 

If all these conditions are met, we call 
PostMessageQ with the private message 
number that was previously obtained 
from RegisterWindowMessage(). (Calls 
to SendMessage() should be avoided in 
hook functions because they can result in 
deadlock conditions.) Finally, we pass the 
event to the next Windows hook proce- 
dure in the chain by calling CallNext- 
HookEx(). 

We're almost done now. We only need 
to add some lines of code to the message 
handler for our application's main win- 
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dow that will detect the private message 
number posted by the callback proce- 
dure. To process this message, we call 
WinHelp() with the conunand HELP_ 
CONTEXT, the pathname for the help 
file, and the identifier that was associated 
with the context string for the menu topic 
in the [MAP] section of the HPJ file. The 
effect of this call is to launch WINHELP 
.EXE, if it isn't already nmning, and the 
menu topic is displayed in the main 
viewer window. The skeleton for all this 
context-sensitive help code can be found 
in Figure 1, and the source code for a ver- 
sion of EXELOOK.EXE that supports 
context-sensitive help can be down- 
loaded from PC MagNet. 

The final step is to export the windows 
hook procedure by adding its name to the 
EXPORTS section of the application's 
module definition (.DBF) file, and then 
rebuild the appUcation. 

BEAOEB FEEDBACK Many of you have 
written about my columns on Windows 
NT and the Windows help system. I've 



selected a few letters to publish here. 

1 appreciate your mentioning simtef] 
your April 13, 1993, article in PC Ma] 
zine (titled "The Hazards of Explo. 
Evolving Environments"), but many 
ers are likely to find the TOPS-20 file sj^ 
tern daunting. Similarly, garbo is run 
U.S. site, and access to it can be finici 
You might want to direct readers to 
mirror site at WasMngton University in 
Louis, wuarchive.wustl.edu. The wuar^ 
chive.wustLedu site mirrors not only 
simtel but a huge number of other sites, 
offering a wealth of programs. The MS- 
DOS partition from simtel is echoed irH 
/mirrors/msdos. There are also MS-DO & 
archives located at archive.msdos.umicft 
.edd. T 

You might also wish to mention to us- 
ers who don't have direct Internet access 
that a mail-based FTP (file transfer proto- 
col) server, BITFTP, exists at Princeton 
University and can be reached via e-mail 
at BITFTP@PUCC.EDU; sending the 
command HELP in the body of an e-mail 
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message will return instructions to you on 
how to use the BITFTP service. 

David O'Donnell 
vialntamet 

In your April 13, 1993, column, you 

give some erroneous advice. 

First, the instructions you supplied to 
use anonynious FTP to retrieve .ZIP files 
from the simtellO archive will result in the 
mangling of whatever file is being downr 
loaded. The simtel20 is one of the few 
anonymous FTP archives where the 
magic word for setting the file type for 
transfer is not "binary. " On simtel20 the 
file type must be declared as "tenex." The 
reasons for this are moderately arcane but 
there is no way around it. 
. Secondly, you point to garbo.uwasa.fi 
as a popular mirror of the simteUO site. 
The garbo.uwasa.fi site does have many 
of the same files as the simtel20 archive, 
but it is not a mirror site; it does not have 
all the same files and it does not have the 
same directory structure. In addition, if the 
majority of the PC Magazine readership 
is in the U.S., steering readers to an archive 
site in Finland could result in costly inter- 
national transfers. 

Two sites that are mirrors of the sim- 
tel20 archive are oak.oakUmd.edu md 
wuarchive.wustl.edu, and both are in 
North America. 

John Schmid 
via Intern^ 

WINDOWS IMl? I'm glad to see someone 
spreading the word that Windows con- 
Uans an excellent built-in viewing tool for 
on-line Help. 

It's unfortunate that the SDK docu- 
ments the common-enough but arcane 
RTF file format the way it does. Microsoft 
could have made things much easier by 
documenting the Windows help authoring 
system in the SDK the same way it docu- 
ments the multimedia viewer for the MDK 
(Multimedia Development Kit). The 
multimedia viewer (that Microsoft uses, 
with some extensions, for such projects as 
CineMania) is, after all, just a superset of 
the WinHelp development environment 
(I suspect that Microsoft is trymg to keep 
this a secret, and that we will see multime- 
dia viewer as the on-line help viewing en- 
gine in future versions of Windows.) 

In case you didn't know, there's an up- 
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date to HC31.EXE posted on Microsoft's 
BBS.Jt's named HCP.EXE, dated April 
17,1992, and uses XMS so you can com- 
pile larger help files without the risk of get- 
ting out-of-memory errors. [This program 
is also available iii the Microsoft Library 
Forum on CompuServe. — R.D.] 

I hope your articles promote better on- 
line helpzBut frankly, I don't think we're 
going to see significant improvement until 
the development community acknowl- 
: edges that on-line help files are technical 
docidmerUs justWc/epririted rnanudls Ond,"^^ 
as such, should be writteh by the technical 
documentation department, not program- 
mers whose primary responsibility needs ■ 
to be with the code. : 

Wayne Hausmann 
via Internet 

Thanks for your recent article in the 
May 11, 1993, issue of PC Magazine. / 
built my first Windows help application 
using WordPerfect for Windows, Version 
5.2. I encountered some differences be- 
tween the two word processors when I 
tried to map your Microsoft Word exam- 
ples into working text: 

• WordPerfect for Windows handily ex- 
ports and imports text in R TF format This 
seems to intUcate that only one copy of a 
help file needs to be maintained; that the 
RTF format can be edited directly, and the 
native WordPerfect format can be forgot- 
ten. However, I have experienced loss of 
some formatting codes when importing 
RTF documents into the editor. Therefore 
I will still abide by your suggestion of edit- 
ing in one format and exporting to the 
other. 

• The # symbol may not be used to num- 
ber footnotes unless the Layout^ootnote/ 

Options/Numbering .Method is set to char- 
acter. Then a string of valid characters 
must be specified in the Layout/Footnote/ 
Options/Characters field. For instance, 
the string "it*$K+" would allow you to 
specify context strings (#) as well as build 
tags, titles, keywords, and browse se- 
quence numbers. 

• Use Tools/Comment/Create in Word- 
Perfect for Windows to insert invisible text 
for hypertext links. Unfortunately, Word- 
Perfect for Windows inserts leading and 
trailing carriage returns around /fte com- 
ment and highlights it with a shadow box; 
despite its ungainly appearance, this 



works. The strikeout and redline^' foht 
styles are interpreted as visible texi/dnd 
they are not suitable for hypertext linlcs^ 

James McNdtmrhr 
via Internet 

The help authoring support tools in 
MSDN CD-ROM that you mentiorti 
your first help file article (April 27,1 
are now available dn the Internet. The Help- 
compiler for 3.0 and 3.1 along wi' 
WHPE (Windows Help Project Editor 
WinWord macros, and other gqg' 
' can be found on ftp.cica.indiana.^ 
/pub/pc/win3/uploads/what.zip (a J$ 
file). The Windows Help Aiit. 
Guide is on the same machines /p^ 
winS/programr/whag.zip co 
guide in WinWord documents, am 
pc/win3/progrttmr/hag.zip con 
guide in the Help format Each fi 
proximately 500K. 

m 

vialrii^ 

Clearly, there's a dearth ofinformatwr^ 
about WinHelp. Which brings me to^d. 
plug for a book I coauthored along with 
Dave Farkas and Joe Welinske: Develop- 
ing Online Help for Windows. It is pub- 
lished by Howard W.Sams Co. 

While the Windows Help Authoring, 
Guide does contain a ton of valuable in- 
formation, it's not very process-orientec^ 
For example, Microsoft gives the m^r^ 
syntax, but doesn't really explain where^g^ 
use macros, or the intricacies of doing 
something like dyruimically changing the 
button binding in a help system. ^ 

In our book, we included more ho^ 
to information, a large section on help 
sign principles, complete SDK-Uke 
mentation, a look at development methods 
ologies, and reviews of the automated help 
tools currently on the market For more 
info, see the WinHelp Forum on CIS for. 
a help file containing a full outline aruL 
chapter summaries. i - 

Scott Boggan 
via CompuServe 

THE IN BOX Please send your com- 
ments, suggestions, or questions to me at 
any of the following e-mail address^: 
PC MagNet: 7224142 
MCI Mail: rduncan 
Internet: duncan@cerLnet □ 



